Code for reproducing "Observationally Constrained Global Warming Hysteresis under CO2 Removal" (Song et al., submitted)

---
### Table of Contents
* [System Requirements](#system-requirements)  
* [Code and Data Structure](#code-and-data-structure)
* [Quick Start](#quick-start)
* [Reproduce the  Analysis](#reproduce-the-analysis)

---
### System Requirements
Code language & version
* Python 3.11 – required for scripts in `Code/Bayesian_EBM/` and `Code/Display/` (Bayesian Energy Balance Model (EBM) calibration and emulation)  

The could should run on any OS supporting Python (Windows/macOS/Linux). It does not require any special or non-standard hardware.

---
### Code and Data Structure
- 📁 root_directory/ - The main folder for all resources
  - 📁 Code/ - Directory of this repository
    - 📁 [util](util)/ - Required libraries for analysis
    - 📁 [Data](Data)/ - Main data storage directory
    - 📁 [Bayesian_EBM](Bayesian_EBM)/ - Bayesian EBM calibration and emulation
    - 📁 [Display](Display)/ - Code for generating Figures and Tables

---
### Quick Start
To reproduce all main-text and supplementary figures and tables, please run each of the following scripts.
Required data should be downloaded as the following zip files and extracted into the corresponding directories:

- 📁 [Data](Data)/ - Main data storage directory  
   - 📁 [Bayesian](Data/Bayesian)/   - Contains data from the following archives: EBM2.zip, EBM3.zip, OBS.zip, OLS.zip, SSP.zip  
   - 📁 [CESM2](Data/CESM2)/         - Contains data from the following archives: CESM2.zip, including post-processed CESM2 abrupt-4xCO2 and abrupt-2xCO2 datasets
   - 📁 [Stats](Data/Stats)/         - Contains data from Stats.zip, including GMST, parameter, processed, and RF (radiative forcing) datasets

- 📁 Code/
    - 📁 [Display](Display)/
      - 📄 [Figure01-04.ipynb] - Main Figures
      - 📄 [FigureS01-12.ipynb] - Supplementary Figures
      - 📄 [TableS01-04.ipynb] - Supplementary Tables

--- 
### Reproduce the Analysis

#### A. Bayesian inference and EBM emulation
Please ensure the following Python packages are installed:  
`arviz`, `matplotlib`, `numpy`, `pandas`, `pymc`, `pytensor`, `numba`, `scipy`, and `netCDF4`.
- A PyMC environment (`pymc_env`) is required for Bayesian inference.  
- Installation guide: [https://www.pymc.io/projects/docs/en/latest/installation.html](https://www.pymc.io/projects/docs/en/latest/installation.html)

Please ensure that the required datasets are available in the specified directories:
- Forcing data: located in Data/Stats/RF
- GMST estimates: located in Data/Stats/GMST
- OHC estimates: located in Data/Stats/processed

To perform Bayesian inference scripts, follow the instructions below:
- For `.ipynb` files — Open in **Jupyter Notebook** or **JupyterLab** and execute them **cell-by-cell**.  
- For `.py` scripts — Run directly from the terminal, for example:
```bash
python3 OBS_6_pymc.py 0-2
```
Here, the numbers indicate the dataset to use:  (0 = 'DCENT', 1 = 'HadCRUT5', 2 = 'Berkeley Earth').

- 📁 Code/
  - 📁 [Bayesian_EBM](Bayesian_EBM)/
    - 📁 [EBM2](Bayesian_EBM/EBM2)/
      - 📄 [EBM_1_pymc.ipynb](Bayesian_EBM/EBM2/EBM_1_pymc.ipynb) — Bayesian inference of EBM2 parameters using ESM output.
      - 📄 [EBM_1_hysteresis.ipynb](Bayesian_EBM/EBM2/EBM_1_hysteresis.ipynb) — Hysteresis calculation.  
      - 📄 [EBM_1_eval.ipynb](Bayesian_EBM/EBM2/EBM_1_eval.ipynb) — EBM2 emulation under abrupt-4xCO2 & Ramp-up/-down scenarios.  

    - 📁 [EBM3](Bayesian_EBM/EBM3)/
      - 📄 [EBM_6_pymc.ipynb](Bayesian_EBM/EBM3/EBM_6_pymc.ipynb) — Bayesian inference of EBM3 parameters using ESM output.
      - 📄 [EBM_6_hysteresis.ipynb](Bayesian_EBM/EBM3/EBM_6_hysteresis.ipynb) — Hysteresis calculation.  
      - 📄 [EBM_6_eval.ipynb](Bayesian_EBM/EBM3/EBM_6_eval.ipynb) — EBM3 emulation under abrupt-4xCO2 & Ramp-up/-down scenarios. 

    - 📁 [OBS](Bayesian_EBM/OBS)/
      - 📄 [OBS_6_pymc.py](Bayesian_EBM/OBS/OBS_6_pymc.py) — Bayesian inference of EBM3 parameters using OBS estimates.
      - 📄 [OBS_6_hysteresis.ipynb](Bayesian_EBM/OBS/OBS_6_hysteresis.ipynb) — Hysteresis calculation.
      - 📄 [OBS_6_eval.ipynb](Bayesian_EBM/OBS/OBS_6_eval.ipynb) — EBM3 emulation under historical radiative forcing.  

    - 📁 [OLS](Bayesian_EBM/OLS)/
      - 📄 [EBM_fitting_OLS.ipynb](Bayesian_EBM/OLS/EBM_fitting_OLS.ipynb) — Ordinary least squares fitting.  

    - 📁 [SSP](Bayesian_EBM/SSP)/
      - 📄 [SSP_6_eval.ipynb](Bayesian_EBM/SSP/SSP_6_eval.ipynb) — EBM3 emulation under SSP radiative forcing.

---
Maintained by __Se-Yong Song__ (sysong619@gmail.com)

Last Update: Oct. 22, 2025